home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3dm / audio / alOpenPort.z / alOpenPort
Encoding:
Text File  |  2002-10-03  |  7.9 KB  |  133 lines

  1.  
  2.  
  3.  
  4. aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm))))                                                aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      alOpenPort - open an audio port
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ddddmmmmeeeeddddiiiiaaaa////aaaauuuuddddiiiioooo....hhhh>>>>
  13.  
  14.      AAAALLLLppppoooorrrrtttt aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((cccchhhhaaaarrrr ****nnnnaaaammmmeeee,,,, cccchhhhaaaarrrr ****ddddiiiirrrreeeeccccttttiiiioooonnnn,,,, AAAALLLLccccoooonnnnffffiiiigggg ccccoooonnnnffffiiiigggg))))
  15.  
  16. PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR
  17.      _n_a_m_e        A port _n_a_m_e is a character string describing the port.  It is
  18.                  intended for human consumption, similar to a window title.
  19.                  Port names have a maximum length of 20 characters.
  20.  
  21.      _d_i_r_e_c_t_i_o_n   Specifies whether the port is for input or output.
  22.  
  23.                  """"rrrr"""" specifies an input port.
  24.  
  25.                  """"wwww"""" specifies an output port.
  26.  
  27.      _c_o_n_f_i_g      Expects an AAAALLLLccccoooonnnnffffiiiigggg, as returned by aaaallllNNNNeeeewwwwCCCCoooonnnnffffiiiigggg((((3333ddddmmmm)))) or
  28.                  aaaallllGGGGeeeettttCCCCoooonnnnffffiiiigggg((((3333ddddmmmm)))).  This structure describes the data format
  29.                  and queue size for the port.
  30.  
  31.                  Passing a null (0) value for _c_o_n_f_i_g yields a port with the
  32.                  default configuration.
  33.  
  34. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  35.      aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm)))) allocates and initializes an audio ppppoooorrrrtttt (AAAALLLLppppoooorrrrtttt). An
  36.      audio port is the mechanism through which an application reads or writes
  37.      real-time audio data.  There are two types of ports: input and output. An
  38.      input port receives a real-time stream of audio data from an audio input
  39.      device. An output port sends a single real-time stream of audio data to
  40.      an output device or devices.
  41.  
  42.      A single application may have multiple ports open simultaneously, or
  43.      multiple applications may have ports open, either sharing audio devices
  44.      or using multiple audio devices. There is, however, a system-dependent
  45.      limit to the total number of audio ports active on a given system.
  46.  
  47.      This limit can be found by retrieving the value of the AL_MAX_PORTS
  48.      parameter on the AL_SYSTEM resource; see aaaallllPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) and
  49.      aaaallllGGGGeeeettttPPPPaaaarrrraaaammmmssss((((3333ddddmmmm)))) for information on how to do this.
  50.  
  51.      As soon as the call to aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt completes successfully, the port is
  52.      considered "open." This means it will be filling or draining audio data
  53.      in real-time at the rate of the audio device to which the port is
  54.      connected. The application must read or write enough data frequently
  55.      enough that the port does not underflow or overflow. Refer to
  56.      aaaallllRRRReeeeaaaaddddFFFFrrrraaaammmmeeeessss((((3333ddddmmmm)))), aaaallllWWWWrrrriiiitttteeeeFFFFrrrraaaammmmeeeessss((((3333ddddmmmm)))), aaaallllDDDDiiiissssccccaaaarrrrddddFFFFrrrraaaammmmeeeessss((((3333ddddmmmm)))), and
  57.      aaaallllZZZZeeeerrrrooooFFFFrrrraaaammmmeeeessss((((3333ddddmmmm)))) for more information on how to read and write audio
  58.      data to and from a port.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm))))                                                aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm))))
  71.  
  72.  
  73.  
  74.      Also note that an open audio port consumes CPU and memory resources even
  75.      if the application is not actively reading or writing audio data. If your
  76.      application is not using an audio port, it is best to close it.
  77.  
  78.      The default port has a 50,000 sample frame stereo buffer, using a 16-bit
  79.      two's complement sample format.
  80.  
  81. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  82.      If successful, aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm)))) returns a non-zero AAAALLLLppppoooorrrrtttt handle for the
  83.      port.  Otherwise, aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt((((3333ddddmmmm)))) returns a null (0) ALport and sets an
  84.      error code, which can be retrieved via oooosssseeeerrrrrrrroooorrrr((((3333CCCC)))).
  85.  
  86.      aaaallllOOOOppppeeeennnnPPPPoooorrrrtttt can fail with the following error codes:
  87.  
  88.      AAAALLLL____BBBBAAAADDDD____CCCCOOOONNNNFFFFIIIIGGGG          _c_o_n_f_i_g is invalid.
  89.  
  90.      AAAALLLL____BBBBAAAADDDD____DDDDIIIIRRRREEEECCCCTTTTIIIIOOOONNNN       _d_i_r_e_c_t_i_o_n is neither "r" nor "w."
  91.  
  92.      AAAALLLL____BBBBAAAADDDD____OOOOUUUUTTTT____OOOOFFFF____MMMMEEEEMMMM      insufficient memory is available to allocate the
  93.                             AAAALLLLppppoooorrrrtttt, or the device has refused the connection
  94.                             for some other reason including:  1) the microcode
  95.                             is not yet loaded on the Indigo R4000 DSP 2)
  96.                             another subcode port is currently writing the same
  97.                             subcode format to the device.
  98.  
  99.      AAAALLLL____BBBBAAAADDDD____DDDDEEEEVVVVIIIICCCCEEEE____AAAACCCCCCCCEEEESSSSSSSS   audio hardware is not available, or is improperly
  100.                             configured.
  101.  
  102.      AAAALLLL____BBBBAAAADDDD____DDDDEEEEVVVVIIIICCCCEEEE          the device given in the config is bad, either
  103.                             because it does not exist, or because it has the
  104.                             wrong direction (input vs. output).
  105.  
  106.      AAAALLLL____BBBBAAAADDDD____NNNNOOOO____PPPPOOOORRRRTTTTSSSS        no audio ports are currently available.
  107.                             AAAALLLL____BBBBAAAADDDD____SSSSAAAAMMMMPPPPFFFFMMMMTTTT the device given in the config does
  108.                             not support the sample format given in the config.
  109.                             This should only occur if a device does not
  110.                             support a subcode sample format.
  111.  
  112. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  113.      alClosePort(3dm), alNewConfig(3dm), alSetConfig(3dm), ALqueryparams(3dm),
  114.      oserror(3C)
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.